TSAP: How to use it

(Carlos Rodrigo, Enrique Solano. LAEFF- Spanish Virtual Observatory)

TSAP (Theoretical Spectral Access Protocol) is a simple protocol designed in order to make collections of theoretical data available in the Virtual Observatory.

Motivation

Theoretical models are widely used in Astronomy. The physical properties of an object can, for instance, be inferred by comparing its observed spectrum to a grid of theoretical spectra. Theoretical models are usually available in the Internet as collection of data files that can be downloaded (in some case with the help of a web form allowing a previous selection of the files of interest) in different formats like ASCII or FITS.

Being fully interoperability one of the major goals for the Virtual Observatory, theoretical models should naturally be included in the VO framework. There are, however two major drawbacks with this:

• VO protocols (SSAP, SIAP, ConeSearch...) are clearly biased towards observational data as they demand positional information as mandatory search parameter. This is meaningless when dealing with theoretical models.

• Depending on the physical problem to be tackled, the particular approach taken by the author of the model or even his/her own personal preferences, the set of parameters used to characterize the model usually differs from one to another.

Very interesting efforts are being done in the direction of defining a data model for Theory, a major topic for the IVOA and Euro-VO Theory Groups. However we felt that it was useful to implement a simple way to make the theoretical models available in the VO even not having yet a unified data model for them.

TSAP was born a as collaboration between ESAVO and SVO. It is inspired in SSAP and its self-describing capability through the format=metadata option. In this way, TSAP can be described as a client-server dialogue where the server describes its contents, the client understands the response and makes that information available to the user.

The TSAP dialogue.

(for now on, just for the sake of clarity, we will use http://modelserver.com/tsap.php as an example of the main URL for the TSAP service, but it should be clear that only the parameters added to the main address are relevant to TSAP)

(1) Metadata

(1.1) The client (VO application, web interface, etc) sends an http query to the server asking for the contents that the server offers:

		http://modelserver.com/tsap.php?format=metadata

(1.2) The server answers the query by sending a VOTable containing information about the server itself, the list of parameters allowed in the query, their description and, optionally, the accepted values or ranges of values.

(1.3) The client receives the VOTable, reads the information and builds a form coherent with the capabilities of the server.

(1.4) The user chooses the values or ranges of values of his/her interest.

(2) Search.

(2.1) The client takes the values chosen by the user and builds the query that is sent to the server

		http://modelserver.com/tsap.php?param1=value1&param2=value2...

(2.2) The server answers the query with a VOTable containing a list with all the particular instances of the model that are available within the specified search criteria. One of the expected fields should be of URL-type to allow the model retrieval.

(3) Model retrieval

(3.1) The client reads the VOTable and shows its contents to the user.

(3.2) The user chooses some of or all the offered instances.

(3.3) The client uses the URL to retrieve the selected datasets and offer them to the user for download, visualization or whatever application the client is designed for.

In this approach, most steps are analogue to those in SSAP, SIAP nd ConeSearch. Actually, whenever possible, the VOTables generated by the model server should be compliant with the requirements of the corresponding observational VO protocols. This means that if, for instance, the server offers theoretical spectra, the output is expected to follow the SSAP specifications as close as possible.

The main contribution of TSAP is in the first step: how the server describes itself and how the client must understand that self-description. Let's describe it in more detail.

Model self-description and metadata interpretation

The main point in this approach is that, when a client asks a TSAP server for its format=metadata, the server must answer with a VOTable containing:

• a general description of the server
• a list of the parameters that are accepted for a search query, together with their descriptions and allowed values or range of values.

 <description>a general text description of the theoretical model
       offered by the server </description>
 <param name=”param1” ucd=”...” datatype=”float”...>
    <description>a short human-readable text description of the
        meaning of this parameter</description>
  </param>

In the particular case of a model described by two parameters (e.g. Teff, logg) this would be:

  <description>Stellar atmosphere model by..., version 1 </description>
  <param name=”teff” ucd=”phys.temperature.effective” units=”K” datatype=”float”>
     <description>Effective temperature for the model in K</description>
  </param>
  <param name=”logg” ucd=”phys.gravity” datatype=”float”>
    <description>Logarithm of the surface gravity</description>
  </param>

The client, reading this VOTable, knows the parameters available for the search as well as their names and descriptions and can build a form like this one:

When the user submits the form, the client must take the values and send a search query to the server:

 http://modelserver.com/tsap.php?param1=value1&...&paramN=valueN

In this example, assuming that the user has chosen a value on 10000 for teff and 2.0 for Logg, the client would send a query like:

 http://modelserver.com/tsap.php?teff=10000&logg=2.0

Ranges of parameters

Queries driven by ranges of parameters are managed by just sending pairs of parameters with the corresponding description:

  <description>Stellar atmosphere model by..., version 1 </description>
 <param name=”teff_min” ucd=”phys.temperature.effective” units=”K” datatype=”float”>
    <description>Min. effective temperature for the model in K</description>
  </param>
  <param name=”teff_max” ucd=”phys.temperature.effective” units=”K” datatype=”float”>
    <description>Max. effective temperature for the model in K</description>
  </param>
  <param name=”logg” ucd=”phys.gravity” datatype=”float”>
    <description>Logarithm of the surface gravity</description>
  </param>

In this case, the client could straightforwardly build a form like:

or it could try to be smart and, noticing that there are two parameters whose names only differ in a substring ("min/max"), assume that they correspond to a range and then build the form as:

In any case, the query should look like this:

 http://modelserver.com/tsap.php?teff_min=1000&teff_max=2000&logg=2

Specifying acceptable values

The server has also the possibility of specifying the accepted values for a certain parameter using the tag <VALUES>.

  <param name=”teff_max” ucd=”phys.temperature.effective” units=”K” datatype=”float”>
     <description>Max. effective temperature for the model in K</description>
     <values>
        <min value=1000/>
        <max value=5000/>
     </values>
  </param>

This information can be used by the client in two ways: (i) for showing it to the user, and (ii) for checking that the values provided by the user in the form are in the permitted range before performing the query.

In many cases, the most useful approach is that the server specifies all the values that it offers for every parameter. That can be done using <option> for each value within the <values> structure.

  <param name=”teff_max” ucd=”phys.temperature.effective” units=”K” datatype=”float”>
    <description>Max. effective temperature for the model in K</description>
    <values>
       <option value=1000/>
       <option value=1100/>
       <option value=1150/>
       ...
       <option value=3500/>
       <option value=4700/>
       <option value=5000/>
    </values>
  </param>

This will allow the client to build a more adequate form, allowing the user to choose only acceptable values, like:

The use of TSAP

Some synthetic spectra models are already available in the VO making use of TSAP. Here we provide some examples (the links go to the format=metadata VOTable for each service).

• ATLAS9 Kurucz ODFNEW/NOVER models
• Models of irradiated accretion disks around PMS stars (D\'Alessio et al)
• Coelho Synthetic stellar library
• The NextGen Model Atmosphere grid
• The COND00 Model Atmosphere grid
• The DUSTY00 Model Atmosphere grid
• UCL stellar atmosphere model
• Sternberg stellar atmosphere model
• Sed@ evolutionary synthesis models
• PEGASE.HR synthetic spectra
• X-ray service prototype

The VOSpec application can access these services and plots the synthetic spectra together with the observed ones.

The VOSED application includes a fitting application based on Bayesian analysis, that, given an observational spectrum, uses TSAP to get what it needs from Kurucz and D'Alessio models, find the model that best fits the observational data and obtain physical parameters for the observed object.

Although the first aim of TSAP was to make theoretical spectra available in the VO, the same approach can be used for any kind of theoretical data. Examples where TSAP is used to make isochrones and evolutionary tracks available in the VO are given here:

• Theoretical Isochrones and evolutionary tracks from NextGen model
• Theoretical Isochrones and evolutionary tracks from COND99 model
• Theoretical Isochrones and evolutionary tracks from DUSTY99 model